Object qualification
In the API signatures, name is the widget name or SmartDataField name of the object you want to manipulate. In some methods, you can supply a namelist, which is a CHARACTER string of one or more widget or SmartDataField names. Separate multiple names with commas without intervening spaces.
Client logic code on the GUI client supports both qualified and unqualified names, as described in the next sections.
Unqualified names
When you supply just the widget names, these are considered unqualified names. The APIs have the ability to resolve unqualified names where there is no ambiguity. Using unqualified names speeds code writing and promotes reuse of code. For example, you can move code with unqualified names from one object to a similar object without changing it.
In the GUI client, unqualified widgets are qualified by a search algorithm based on where the code containing the unqualified reference is written.
The following table describes how each type of object finds objects with unqualified instance names:
|
Object type
|
Qualification method
|
Unqualified examples
|
|
Container
|
Does not support unqualified names.
|
NA
|
|
Browse
|
Checks for object in the browse first. Then checks for widgets (data fields only) in viewers with the same data source, using the first widget found.
|
ordernum
orderdate
|
|
Viewer
|
Checks for a widget in that object first (data fields and local fields).
Then checks for widgets (data fields only) in sibling viewers (viewers linked to the viewers data source).
Progress Dynamics uses the first widget found.
|
orderfullo.ordernum
orderlinefullo.ordernum
|
The search algorithm is complicated a bit by references to SBO fields. Suppose a viewer displays fields from an SBO that draws data from several SDOs. To fully qualify which data source (SDO) fields are sources for viewer fields, the field is qualified by the SDO name: SDOname.fieldname. For example, orderfullo.ordernum and orderlinefullo.ordernum.
So, to deal effectively with this use case, first, the API treats names with a single qualifier as a field name qualified with an SDO name. If it fails to find the named widget, it then treats the first qualifier as an SDO name qualifier.
In an SBO-based viewer, an unqualified widget name will find a local widget with a matching name before looking in the SBO for a qualified field. The search to locate the widget in data-source siblings is done after checking whether the unqualified field matches an SBO field. The unqualified search will return a handle even if the request is ambiguous and more than one field matches the unqualifed name, so the qualifier should be used to guarantee precision. The qualified search is also faster.
Qualified names
Use qualified names when writing complex code or when the rules for resolving unqualified names does not meet the needs of your application.
Object names can be qualified by one of several methods. They are searched depending upon the location of the client logic. If the first entry in a list of objects is qualified and others in the list are not, the first qualifier extends as a default to other unqualified items in the list. See the following table:
|
Qualification
|
Description
|
Examples
|
|
With the Self keyword.
|
For a browse or viewer, Progress Dynamics checks for a widget (data fields and local fields) in that object only. It uses everything after self. as the field name. In the second example, orderfullo.orderdate is the field name. For a container, there is no support for the self qualifier.
|
|
|
With the Browse keyword.
|
For a browse, Progress Dynamics checks for a widget in that object only. For a viewer, Progress Dynamics gets the viewer’s data source and checks for a widget in its browse data target. For a container, there is no support for the browse qualifier.
Note: Browse is an allowed 4GL variable. You cannot use a widget name of “Browse” with the client logic API.
|
|
|
With an SDO name and Browse keyword.
|
For a browse or viewer, Progress Dynamics finds the SDO in the object’s container source and checks for a widget in the SDO’s browse data target. For a container, Progress Dynamics checks for a widget in the SDO’s browse data target.
|
|
|
With an SDO name.
|
For a browse or viewer, Progress Dynamics finds the SDO in the object’s container source and checks for a widget in the SDO’s data targets, but checks the update source first. The first widget found is used. For a container, Progress Dynamics checks for a widget in the SDO’s data targets but checks the update source first. Progress Dynamics uses the first widget found.
|
|
|
With an SBO name and Browse keyword.
|
Any use of a field name from an SBO must be qualified with an SDO name: SBOname.SDOname.fieldname. In a browse or viewer, Progress Dynamics finds the SBO in the object container source and checks for a widget SBO’s browse data target. In a container, Progress Dynamics checks for a widget in the SBO’s browse data target.
|
|
|
With an instance name.
|
The instance name must be a browse, viewer, or visual object that supports the internalWidgetHandle function. It uses everything after the instancename. as the field name. In the second example, orderfullo.shipdate is the field name. For a browser or viewer, Progress Dynamics gets the object’s container source and checks for a widget in that object instance within its container. For a container, Progress Dynamics checks for a widget in that object instance of the container.
|
|
|
With an SBO name.
|
Any use of a field name from an SBO must be first qualified with an SDO name: SBOname.SDOname.fieldname.
If the viewer qualifies the fields with an SDO name (because they have been defined for an SBO), Progress Dynamics uses the SDO name in the search, otherwise it uses only the field name.
In a browser or viewer, Progress Dynamics finds the SBO in the object container source and checks for a widget in the SBO’s data targets that map to the SDO, but checks the update source first. The first widget found is used.
In a container, Progress Dynamics checks for a widget in the SBO’s data targets that map to the SDO, but checks the update source first. The first widget found is used.
|
|